MacFormat 1995 December/macformat-031.iso/mac/Internet/HTML Software/BBEdit HTML Tools v1.3.1/Documentation/User's Markup Info.txt

Text File | 1995-03-06 | 14.7 KB | 402 lines | [TEXT/R*ch]

User's Markup Tool - part of the BBEdit HTML Tools package.
©1994 Lindsay Davies
email: [e-mail]


Status:                Semi-informal release pending feedback :-)
Last updated:        22 Aug 1994



USER DEFINED MARKUP ROUTINES
-------------------------------------------------------------------------

This tool will help those people who regularly have to edit HTML
documents. It allows you to define up to 10 'styles' that can be applied
to any part of your text.

(Background note: This tool started off with a rather more limited
scope in mind. It seems that in developing it, it has changed from being
a tool for storing simple markup styles to a simple macro package. So bear
in mind that macros weren't its original objective, and forgive its
rather clumsy design!).




Introduction:
-------------------------------------------------------------------------

To define your style, bring up the 'User Styles' tool, and you will see a
number of undefined buttons. To create a label and definition for your
style, simply click on a button and fill out the 'Label' and 'Definition'
fields (The definition field isn't yet labelled).

The best way to introduce the tool is with a worked through example.
Suppose that we have a style for certain section headings that requires
marking up like this:

   <H2><I>My Heading</I></H2>
   <HR>

This would normally involve 4 operations (one for each of the
tags involved, and one for the return before the <HR> tag).

To define your own style to do this automatically, Make your definition
as follows:

   <H2><I>…</I></H2>\r<HR>

Working through this example we have the opening Heading tag,
the opening Italic tag, and then we have the important part, the
ellipsis. You type the ellipsis by using Option-; not by typing 3
periods. The ellipsis is the character that represents your current
selection. All text before the ellipsis goes before your selection, and
of course, everything after the ellipsis follows after the current
selection.

So after the ellipsis we have the closing Italic and Heading tags.
Following on from this is \r which represents a return character.
Finally we have the horizontal rule tag.

So if you select your text, eg

    My Heading

...and then apply this style to it, it will be marked up exactly as the
first example was, but in one operation.

If you have number of headings to mark up, then you won't want to keep
having the dialog box keep appearing. This is where the checkbox in the
bottom left of the dialog comes in. Check this if you want the
currently selected style to be applied when choose the 'User Styles' tool
from the menu WITHOUT the dialog appearing. To bring the dialog
back, hold the CONTROL key down while selecting the tool.

This is useful if you assign a command-key to the tool (using the
excellent BBXKeys extension (from Sumex), or with the commercial version
of BBEdit). You can then just use command-<whatever key you want> to
markup the current selection with your chosen style.

OK, that's the basics. If you don't want to know any more, then save the
next bit till later! You may however wish to have a look at the examples
at the end of this document, which will give you an idea of the sorts of
things that you can do.



Intermediate Stuff:
-------------------------------------------------------------------------
In your style definition, you can put in certain placeholders. You have
already met the one for a return - \r. There are some others available to
help you with your creative impluses:

  Placeholder             Function
     \r                    Inserts return character
     \t                    Inserts tab character
     \c                    Inserts clipboard (eg whatever has been
                             most recently copied or cut.
     \b                    Inserts the contents of the buffer
     \…                    Inserts an ellipsis
     \\                    Inserts a slash
     \!                    Inserts an exclamation mark
     \"                    Inserts a quote
     \s                    Inserts the current selection
     \d                    Inserts the current date (short format)
     \D                    Inserts the current date (long format)


So far so simple (?). Now for some more stuff...



Slightly More Difficult Stuff:
-------------------------------------------------------------------------
I guess I'm lazy, but I thought I'd add a few extra things to help me
when I am marking up. So the next thing to learn about are the 'commands'
that you can insert into your style definition.

The commands simply allow you to manipulate and edit the current
selection. Stringing a series of commands together can allow you to
perform quite complex tasks.

Again, we'll work through an example. The previous example relied
upon you selecting the text to be marked up. Much easier would be to
simply click in the text, and have your definition automatically select
the text for you.

So, referring back to the previous example, if we clicked in the middle
of the word 'heading', we might want to select the whole line before
applying the markup to it.

This is done using the command "!SL" (without the quotes). This reads as

        !    <--    The next 2 characters represent a command and parameter
        S     <--    'Select' command
        L    <--    This parameter means select the current line.

So the new definition would be:

   !SL<H2><I>...</I></H2>\r<HR>

Which reads as 'select the line, insert the '<H2><I>' bits before
the current selection, and insert  '</I></H2>' and a return character and
'<HR>' after the selection. (Hopefully you are still with me - there's more!).

List of Commands:

Command            Function
=======         ========
Selecting
    !SW            select the word that the insertion point is in
    !SL            select the line that the insertion point is in
    !SP            select the paragraph that the insertion point is in
    !SD            select the whole document.
    !SC            select all text and tags of a Container.
    !ST            select all Text within a container.


Copying
    !CC            copy the current selection to the clipboard
    !CB            copy the current selection to the Buffer.
    !CA            append the current selection to the clipboard
    !CT"xyz"    append the text 'xyz' to the clipboard (all the placeholders
                mentioned above can be used in this string).
    !CZ            clear the clipboard

Extending
    !EF"xyz"    extends the selection forwards to start of string "xyz"
    !E^            extend to start of line
    !E$            extend to end of line

Inserting
    !IS"xyz"    insert text "xyz" at start of selection
    !IE"xyz"    insert text "xyz" at end of selection
    !IR"xyz"    insert "xyz" Replacing the selection

Finding
    !FN"abc"    find next occurrence of "abc" where "abc" can include the
                simple grep patterns...
                '.'     matches any character
                '#'     matches any numeric character
                '.*'     matches zero or more characters (Note that although standard
                        Grep is limited to a single line, in this case the pattern can
                        span the entire document.
                '#*'    match zero or more numeric characters
                '#+'    match one or more numeric characters

    !FA"abc"    same as above, but will find all matches of "abc" in the
                document.

Place Insertion Point
    !@E            insertion point at end of selection
    !@S            insertion point at start of selection
    !@T            insertion point at top of document
    !@B            insertion point at bottom of document
    !@L            insertion point at next line
    !@P            insertion point at next paragraph
    !@^            insertion point at start of line
    !@$            insertion point at end of line

Case
    !KR            raise the case of the selection
    !KL            lower the case of the selection
    !KT            make all HTML tags upper case

Deleting
    !DS            delete the current selection
    !DX            delete current selection + surrounding space
    !DC            delete the clipboard

Misc
    !Nx            set the next default definition to the number x (0 - 9)
                specified.
    !|x            Run macro x after the current one has completed.
    !BP            Beep - useful in some cases when you are debugging a macro.
    !§k            Switch searching case sensitivity ON
    !§K            Switch searching case sensitivity OFF (Default)

Note that you can use Command-. to exit from any series of commands
you may be using.

*    Commands may have a single space between them to aid legibility.

*    The sequence of commands is limited to 255 characters in length.

A good example is having a list of delegate names for a conference. I
want to have a main document with all the names, but have links from the
names to vanity pages for each of them. In addition, I would like the
names to be anchors. The names of the vanity pages are all in the format
surname.html in a directory called 'vanity', and using the surname for
the anchor name. eg:

Before:                After:

Joe Bloggs            <A NAME="Bloggs" HREF="/vanity/Bloggs.html">Joe Bloggs</A>
University of X        University of X
email: user@host    email: user@host


This would normally require a fair bit of mouse and keyboard work to do,
especially for a ist of 30 or so delegates. Better still would be to
create a style definition that would do it all for me. eg:

    !SW!CC!SL!IS"<A NAME=\"\c\" HREF=\"/vanity/\c.html\">"!IE"</A>"

Assuming that I have clicked anywhere in the surname (ie 'Bloggs'),
this definition reads as:

    !SW                    Select the Word (ie 'Bloggs')
    !CC                    Copy the selection
    !SL                    Select the Line.
    !IS"<A NAME=\"        insert this text before the selection (note '\"' is
                        required to enter a quote.)
    \c                    insert the clipboard (ie 'Bloggs)
    \" HREF=\"/vanity/    insert this text
    \c                    again, insert the clipbaord
    .html\">"            insert this text
    !IE"</A>"            and insert this text after the selection to finish off.


So, it doesn't look pretty, but it can be quite useful. If you want
anything more powerful, then you really need to get stuck into GREP or
PERL.

To recognise that you sometimes want to follow one style with
another, you can tell your definition which definition to use next.

Using the above example, I could have the definition just described to
mark up the name. I might then wish to have another definition to mark up
the email address. By adding !N2 in front of the first definition, the
next time the tool is used, definition 2 will be the default. (and if
_that_ definition includes a !N1, then repeated use of the tool will
cycle through these definitions 1 and 2.)


Obfuscation time...
-------------------------------------------------------------------------

There will be occasions when you want to perform a series of tasks. You
could allocate them all to different macros, but if they are all meant to
work together, this would be a waste of space.

You can therefore string together seqences of commands into segments
within a definition. To delineate a segment, type a bullet. You will see
that the next segment will start on a new line, and be prefixed by a bullet.

A simple example of this in use would be the situation where you wanted
to compile a list of all anchors in your document. The list will be
compiled on the clipboard, so the first thing you would need to do is to
clear it of any current text.

You will then want to find all anchors, so search for all text starting
with "<A " and ending with "</A>". If it is found, it will be selected,
and we want to append the selection and a return (so that all anchors
start on a new line) to the clipboard. You then need to move the
insertion point to the end of the selection so that the next iteration
won't simply select the same part again. Just to illustrate the point
further, when this second sequence has finished, we want to beep to
signify that we have come to the end.

The macro itself...

        !DC
        •!FA"<A .*</A>" !CT"\s\r"!@E
        •!BP

Note that there are three segments here - the first one that deletes the
clipboard only wants to be performed once. The newline and bullet
delineate the second segment, which iterates through the document
finding and appending the data to the clipboard. Only when this has
complete will the third segment be invoked, and the machine will beep.


Examples
-------------------------------------------------------------------------

Well, that's probably clear as mud, so here are some examples:


-------------------------------------------------------------------------
•  To embolden a word (just click anywhere in the word you want to
   embolden)

    !SW !IS"<B>" !IE"</B>"        Select the word, insert <B> at the start of the
                                selection, insert </B> at the end of the selection.

-------------------------------------------------------------------------
•  To embolden a line:

    !SL !IS"<B>" !IE"</B>"        Exactly the same, but we use !SL instead of !SW.

-------------------------------------------------------------------------
•  To add paragraph tags to a paragraph:

    !SP !IS"<P>" !IE"</P>"            Select paragraph, insert <P> at the end of the selection.

-------------------------------------------------------------------------
•  To make a word into a named anchor:

    !SW !CC !IS"<A NAME="\c">" !IE"</A>"

    Select the word, copy it, insert the tag, inserting the clipboard between the quotes,
    and inserting the closing tag at the end of the selection.

-------------------------------------------------------------------------
•  To remove the current tags from around some text:

    !ST !CC !SC !IR"\c"        Select text up to tags, copy it, select containing tags
                            as     well, insert replacing the selection with what was
                            just copied.

-------------------------------------------------------------------------
•  To mark up glossary items (which are on consecutive lines):

        !SL !IS"<DT>" !FN"\r" !@E !IS"<DD>"

        Select line, Insert "<DT>" at the start of the selection, Find the next
        return character, move the insertion point after it, insert "<DD>" at
        the insertion point.

-------------------------------------------------------------------------
•  Copy all lines containing "BBEdit" to the clipboard

        !CZ                                    Clear the clipboard
        •!FA"BBEdit" !SL !CT"\s\r"            Find all occurrences of "BBEdit",
                                            Select the line, Copy-append Text containing
                                            the current selection and a carriage return.

-------------------------------------------------------------------------
•  Copy all lines containing "BBEdit", regarding case, to the
clipboard

        !CZ!§k                                Clear the clipboard, set case switch ON
        •!FA"BBEdit" !SL !CT"\s\r"            Find all occurrences of "BBEdit",
                                            Select the line, Copy-append Text containing
                                            the current selection and a carriage return.

-------------------------------------------------------------------------
•  Compile and Insert a list of all the headings in a document

        !CZ!@T
        •!FN"<MENU>"!@S!FS"/MENU>"!FS"\r"!DS
        •!FA"<H#>"!@E!ST!CB!CT"<LI>\t<A HREF=\"#\b\">\b</A>\r"
        •!@T!FN"</H1>"!@E!IS"\r<MENU>\r\c</MENU>"!B3


-------------------------------------------------------------------------
•  To change the title of your document to word capitalization

        !@T !FN"<TITLE>" !FS"</TITLE>" !KW    Move insertion point to the top of the doc.
                                            Find next occurrence of <TITLE>. Extend
                                            selection to "</TITLE>", change case of
                                            selection to Word Capitalization.



(Last updated: Monday, March 6, 1995)


Lindsay Davies,
email:    [e-mail]